<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Zend_Db_Table_Rowset - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.db.table.rowset.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.db.table.rowset.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.db.table.row.html">Zend_Db_Table_Row</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.db.html">Zend_Db</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.db.table.relationships.html">Zend_Db_Table Relationships</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.db.table.rowset" class="section"><div class="info"><h1 class="title">Zend_Db_Table_Rowset</h1></div>
    

    <div class="section" id="zend.db.table.rowset.introduction"><div class="info"><h1 class="title">Introduction</h1></div>
        

        <p class="para">
            When you run a query against a Table class using the  <span class="methodname">find()</span> or
             <span class="methodname">fetchAll()</span> methods, the result is returned in an object of type
            <span class="classname">Zend_Db_Table_Rowset_Abstract</span>. A Rowset contains a collection of
            objects descending from <span class="classname">Zend_Db_Table_Row_Abstract</span>. You can
            iterate through the Rowset and access individual Row objects, reading or modifying data
            in the Rows.
        </p>
    </div>

    <div class="section" id="zend.db.table.rowset.fetch"><div class="info"><h1 class="title">Fetching a Rowset</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Db_Table_Abstract</span> provides methods
             <span class="methodname">find()</span> and  <span class="methodname">fetchAll()</span>, each of which
            returns an object of type <span class="classname">Zend_Db_Table_Rowset_Abstract</span>.
        </p>

        <div class="example" id="zend.db.table.rowset.fetch.example"><div class="info"><p><b>Example #1 Example of fetching a rowset</b></p></div>
            

            <pre class="programlisting brush: php">
$bugs   = new Bugs();
$rowset = $bugs-&gt;fetchAll(&quot;bug_status = &#039;NEW&#039;&quot;);
</pre>

        </div>
    </div>

    <div class="section" id="zend.db.table.rowset.rows"><div class="info"><h1 class="title">Retrieving Rows from a Rowset</h1></div>
        

        <p class="para">
            The Rowset itself is usually less interesting than the Rows that it contains. This
            section illustrates how to get the Rows that comprise the Rowset.
        </p>

        <p class="para">
            A legitimate query returns zero rows when no rows in the database match the query
            conditions. Therefore, a Rowset object might contain zero Row objects. Since
            <span class="classname">Zend_Db_Table_Rowset_Abstract</span> implements the
            <span class="classname">Countable</span> interface, you can use  <span class="methodname">count()</span>
            to determine the number of Rows in the Rowset.
        </p>

        <div class="example" id="zend.db.table.rowset.rows.counting.example"><div class="info"><p><b>Example #2 Counting the Rows in a Rowset</b></p></div>
            

            <pre class="programlisting brush: php">
$rowset   = $bugs-&gt;fetchAll(&quot;bug_status = &#039;FIXED&#039;&quot;);

$rowCount = count($rowset);

if ($rowCount &gt; 0) {
    echo &quot;found $rowCount rows&quot;;
} else {
    echo &#039;no rows matched the query&#039;;
}
</pre>

        </div>

        <div class="example" id="zend.db.table.rowset.rows.current.example"><div class="info"><p><b>Example #3 Reading a Single Row from a Rowset</b></p></div>
            

            <div class="example-contents"><p>
                The simplest way to access a Row from a Rowset is to use the
                 <span class="methodname">current()</span> method. This is particularly appropriate when the
                Rowset contains exactly one Row.
            </p></div>

            <pre class="programlisting brush: php">
$bugs   = new Bugs();
$rowset = $bugs-&gt;fetchAll(&quot;bug_id = 1&quot;);
$row    = $rowset-&gt;current();
</pre>

        </div>

        <p class="para">
            If the Rowset contains zero rows,  <span class="methodname">current()</span> returns
            <acronym class="acronym">PHP</acronym>&#039;s <b><tt>NULL</tt></b> value.
        </p>

        <div class="example" id="zend.db.table.rowset.rows.iterate.example"><div class="info"><p><b>Example #4 Iterating through a Rowset</b></p></div>
            

            <div class="example-contents"><p>
                Objects descending from <span class="classname">Zend_Db_Table_Rowset_Abstract</span>
                implement the <span class="classname">SeekableIterator</span> interface, which means you can
                loop through them using the  <span class="methodname">foreach()</span> construct. Each value
                you retrieve this way is a <span class="classname">Zend_Db_Table_Row_Abstract</span> object
                that corresponds to one record from the table.
            </p></div>

            <pre class="programlisting brush: php">
$bugs = new Bugs();

// fetch all records from the table
$rowset = $bugs-&gt;fetchAll();

foreach ($rowset as $row) {

    // output &#039;Zend_Db_Table_Row&#039; or similar
    echo get_class($row) . &quot;\n&quot;;

    // read a column in the row
    $status = $row-&gt;bug_status;

    // modify a column in the current row
    $row-&gt;assigned_to = &#039;mmouse&#039;;

    // write the change to the database
    $row-&gt;save();
}
</pre>

        </div>

        <div class="example" id="zend.db.table.rowset.rows.seek.example"><div class="info"><p><b>Example #5 Seeking to a known position into a Rowset</b></p></div>
            

            <div class="example-contents"><p>
                <span class="classname">SeekableIterator</span> allows you to seek to a position that you
                would like the iterator to jump to. Simply use the  <span class="methodname">seek()</span>
                method for that. Pass it an integer representing the number of the Row you would
                like your Rowset to point to next, don&#039;t forget that it starts with index 0. If the
                index is wrong, ie doesn&#039;t exist, an exception will be thrown. You should use
                 <span class="methodname">count()</span> to check the number of results before seeking to a
                position.
            </p></div>

            <pre class="programlisting brush: php">
$bugs = new Bugs();

// fetch all records from the table
$rowset = $bugs-&gt;fetchAll();

// takes the iterator to the 9th element (zero is one element) :
$rowset-&gt;seek(8);

// retrieve it
$row9 = $rowset-&gt;current();

// and use it
$row9-&gt;assigned_to = &#039;mmouse&#039;;
$row9-&gt;save();
</pre>

        </div>

        <p class="para">
             <span class="methodname">getRow()</span> allows you to get a specific row in the Rowset,
            knowing its position; don&#039;t forget however that positions start with index zero. The
            first parameter for  <span class="methodname">getRow()</span> is an integer for the position
            asked. The second optional parameter is a boolean; it tells the Rowset iterator if
            it must seek to that position in the same time, or not (default is
            <b><tt>FALSE</tt></b>). This method returns a
            <span class="classname">Zend_Db_Table_Row</span> object by default. If the
            position requested does not exist, an exception will be thrown. Here is an example:
        </p>

        <pre class="programlisting brush: php">
$bugs = new Bugs();

// fetch all records from the table
$rowset = $bugs-&gt;fetchAll();

// retrieve the 9th element immediately:
$row9-&gt;getRow(8);

// and use it:
$row9-&gt;assigned_to = &#039;mmouse&#039;;
$row9-&gt;save();
</pre>


        <p class="para">
            After you have access to an individual Row object, you can manipulate the Row using
            methods described in <a href="zend.db.table.row.html" class="link">Zend_Db_Table_Row</a>.
        </p>
    </div>

    <div class="section" id="zend.db.table.rowset.to-array"><div class="info"><h1 class="title">Retrieving a Rowset as an Array</h1></div>
        

        <p class="para">
            You can access all the data in the Rowset as an array using the
             <span class="methodname">toArray()</span> method of the Rowset object. This returns an array
            containing one entry per Row. Each entry is an associative array having keys that
            correspond to column names and elements that correspond to the respective column values.
        </p>

        <div class="example" id="zend.db.table.rowset.to-array.example"><div class="info"><p><b>Example #6 Using toArray()</b></p></div>
            

            <pre class="programlisting brush: php">
$bugs   = new Bugs();
$rowset = $bugs-&gt;fetchAll();

$rowsetArray = $rowset-&gt;toArray();

$rowCount = 1;
foreach ($rowsetArray as $rowArray) {
    echo &quot;row #$rowCount:\n&quot;;
    foreach ($rowArray as $column =&gt; $value) {
        echo &quot;\t$column =&gt; $value\n&quot;;
    }
    ++$rowCount;
    echo &quot;\n&quot;;
}
</pre>

        </div>

        <p class="para">
            The array returned from  <span class="methodname">toArray()</span> is not updateable. That is,
            you can modify values in the array as you can with any array, but changes to the array
            data are not propagated to the database.
        </p>
    </div>

    <div class="section" id="zend.db.table.rowset.serialize"><div class="info"><h1 class="title">Serializing and Unserializing a Rowset</h1></div>
        

        <p class="para">
            Objects of type <span class="classname">Zend_Db_Table_Rowset_Abstract</span> are serializable.
            In a similar fashion to serializing an individual Row object, you can serialize a Rowset
            and unserialize it later.
        </p>

        <div class="example" id="zend.db.table.rowset.serialize.example.serialize"><div class="info"><p><b>Example #7 Serializing a Rowset</b></p></div>
            

            <div class="example-contents"><p>
                Simply use <acronym class="acronym">PHP</acronym>&#039;s  <span class="methodname">serialize()</span> function to
                create a string containing a byte-stream representation of the Rowset object
                argument.
            </p></div>

            <pre class="programlisting brush: php">
$bugs   = new Bugs();
$rowset = $bugs-&gt;fetchAll();

// Convert object to serialized form
$serializedRowset = serialize($rowset);

// Now you can write $serializedRowset to a file, etc.
</pre>

        </div>

        <div class="example" id="zend.db.table.rowset.serialize.example.unserialize"><div class="info"><p><b>Example #8 Unserializing a Serialized Rowset</b></p></div>
            

            <div class="example-contents"><p>
                Use <acronym class="acronym">PHP</acronym>&#039;s  <span class="methodname">unserialize()</span> function to
                restore a string containing a byte-stream representation of an object. The function
                returns the original object.
            </p></div>

            <div class="example-contents"><p>
                Note that the Rowset object returned is in a <em class="emphasis">disconnected</em>
                state. You can iterate through the Rowset and read the Row objects and their
                properties, but you cannot change values in the Rows or execute other methods that
                require a database connection (for example, queries against related tables).
            </p></div>

            <pre class="programlisting brush: php">
$rowsetDisconnected = unserialize($serializedRowset);

// Now you can use object methods and properties, but read-only
$row = $rowsetDisconnected-&gt;current();
echo $row-&gt;bug_description;
</pre>

        </div>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Why do Rowsets unserialize in a disconnected state?</b><br /></span>
            

            <p class="para">
                A serialized object is a string that is readable to anyone who possesses it. It
                could be a security risk to store parameters such as database account and password
                in plain, unencrypted text in the serialized string. You would not want to store
                such data to a text file that is not protected, or send it in an email or other
                medium that is easily read by potential attackers. The reader of the serialized
                object should not be able to use it to gain access to your database without knowing
                valid credentials.
            </p>
        </p></blockquote>

        <p class="para">
            You can reactivate a disconnected Rowset using the  <span class="methodname">setTable()</span>
            method. The argument to this method is a valid object of type
            <span class="classname">Zend_Db_Table_Abstract</span>, which you create. Creating a Table object
            requires a live connection to the database, so by reassociating the Table with the
            Rowset, the Rowset gains access to the database. Subsequently, you can change values in
            the Row objects contained in the Rowset and save the changes to the database.
        </p>

        <div class="example" id="zend.db.table.rowset.serialize.example.set-table"><div class="info"><p><b>Example #9 Reactivating a Rowset as Live Data</b></p></div>
            

            <pre class="programlisting brush: php">
$rowset = unserialize($serializedRowset);

$bugs = new Bugs();

// Reconnect the rowset to a table, and
// thus to a live database connection
$rowset-&gt;setTable($bugs);

$row = $rowset-&gt;current();

// Now you can make changes to the row and save them
$row-&gt;bug_status = &#039;FIXED&#039;;
$row-&gt;save();
</pre>

        </div>

        <p class="para">
            Reactivating a Rowset with  <span class="methodname">setTable()</span> also reactivates all the
            Row objects contained in that Rowset.
        </p>
    </div>

    <div class="section" id="zend.db.table.rowset.extending"><div class="info"><h1 class="title">Extending the Rowset class</h1></div>
        

        <p class="para">
            You can use an alternative concrete class for instances of Rowsets
            by extending <span class="classname">Zend_Db_Table_Rowset_Abstract</span>. Specify the custom
            Rowset class by name either in the <var class="varname">$_rowsetClass</var>
            protected member of a Table class, or in the array argument of the
            constructor of a Table object.
        </p>

        <div class="example" id="zend.db.table.rowset.extending.example"><div class="info"><p><b>Example #10 Specifying a custom Rowset class</b></p></div>
            

            <pre class="programlisting brush: php">
class MyRowset extends Zend_Db_Table_Rowset_Abstract
{
    // ...customizations
}

// Specify a custom Rowset to be used by default
// in all instances of a Table class.
class Products extends Zend_Db_Table_Abstract
{
    protected $_name = &#039;products&#039;;
    protected $_rowsetClass = &#039;MyRowset&#039;;
}

// Or specify a custom Rowset to be used in one
// instance of a Table class.
$bugs = new Bugs(array(&#039;rowsetClass&#039; =&gt; &#039;MyRowset&#039;));
</pre>

        </div>

        <p class="para">
            Typically, the standard <span class="classname">Zend_Db_Rowset</span> concrete class is
            sufficient for most usage. However, you might find it useful
            to add new logic to a Rowset, specific to a given Table.
            For example, a new method could calculate an aggregate
            over all the Rows in the Rowset.
        </p>

        <div class="example" id="zend.db.table.rowset.extending.example-aggregate"><div class="info"><p><b>Example #11 Example of Rowset class with a new method</b></p></div>
            

            <pre class="programlisting brush: php">
class MyBugsRowset extends Zend_Db_Table_Rowset_Abstract
{
    /**
     * Find the Row in the current Rowset with the
     * greatest value in its &#039;updated_at&#039; column.
     */
    public function getLatestUpdatedRow()
    {
        $max_updated_at = 0;
        $latestRow = null;
        foreach ($this as $row) {
            if ($row-&gt;updated_at &gt; $max_updated_at) {
                $latestRow = $row;
            }
        }
        return $latestRow;
    }
}

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = &#039;bugs&#039;;
    protected $_rowsetClass = &#039;MyBugsRowset&#039;;
}
</pre>

        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.db.table.row.html">Zend_Db_Table_Row</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.db.html">Zend_Db</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.db.table.relationships.html">Zend_Db_Table Relationships</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.db.html">Zend_Db</a></li>
  <li><a href="zend.db.adapter.html">Zend_Db_Adapter</a></li>
  <li><a href="zend.db.statement.html">Zend_Db_Statement</a></li>
  <li><a href="zend.db.profiler.html">Zend_Db_Profiler</a></li>
  <li><a href="zend.db.select.html">Zend_Db_Select</a></li>
  <li><a href="zend.db.table.html">Zend_Db_Table</a></li>
  <li><a href="zend.db.table.row.html">Zend_Db_Table_Row</a></li>
  <li class="active"><a href="zend.db.table.rowset.html">Zend_Db_Table_Rowset</a></li>
  <li><a href="zend.db.table.relationships.html">Zend_Db_Table Relationships</a></li>
  <li><a href="zend.db.table.definition.html">Zend_Db_Table_Definition</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>